﻿using Sage.MarkdownRenderer.Html;

namespace Sage.MarkdownRenderer
{
    /// <summary>
    /// WebView2 内容管理器配置选项
    /// </summary>
    /// <remarks>
    /// <para>该配置类提供了对 WebViewManager 各项功能的详细控制，包括主题设置、安全配置、用户交互限制等。</para>
    /// <para>所有配置项都有合理的默认值，可以根据具体需求进行调整。</para>
    /// </remarks>
    public class MarkdownViewManagerOptions
    {
        #region 主题和显示配置

        /// <summary>
        /// 默认主题模式
        /// </summary>
        /// <value>
        /// 设置 WebView 的默认主题显示模式
        /// <list type="bullet">
        /// <item><description><see cref="ThemeMode.Auto"/>: 自动模式，跟随系统主题</description></item>
        /// <item><description><see cref="ThemeMode.Light"/>: 明亮模式，使用浅色主题</description></item>
        /// <item><description><see cref="ThemeMode.Dark"/>: 暗黑模式，使用深色主题</description></item>
        /// </list>
        /// </value>
        /// <remarks>
        /// 默认值为 <see cref="ThemeMode.Auto"/>，会根据系统设置自动选择合适的主题。
        /// 可以通过 <see cref="MarkdownViewManager.SetThemeAsync"/> 方法在运行时动态更改。
        /// </remarks>
        public ThemeMode Theme { get; set; } = ThemeMode.Auto;

        /// <summary>
        /// 默认空内容显示文本
        /// </summary>
        /// <value>当没有内容显示时的提示文本</value>
        /// <remarks>
        /// <para>该文本会在以下情况下显示：</para>
        /// <list type="bullet">
        /// <item><description>调用 MarkdownViewManager.ShowEmptyContentAsync 且未指定消息时</description></item>
        /// <item><description>显示 Markdown 内容但内容为空时</description></item>
        /// <item><description>其他需要显示空状态的场景</description></item>
        /// </list>
        /// <para>如果设置为 null 或空字符串，将使用硬编码的默认值。</para>
        /// </remarks>
        public string DefaultEmptyText { get; set; } = "暂无可用内容显示";

        #endregion

        #region 导航和链接配置

        /// <summary>
        /// 启用外部浏览器打开超链接
        /// </summary>
        /// <value>
        /// <c>true</c>: 拦截 http/https 链接并在系统默认浏览器中打开<br/>
        /// <c>false</c>: 允许链接在 WebView2 内部导航
        /// </value>
        /// <remarks>
        /// <para><strong>启用时的行为：</strong></para>
        /// <list type="bullet">
        /// <item><description>用户点击 http/https 链接时，会取消 WebView2 内的导航</description></item>
        /// <item><description>自动调用系统默认浏览器打开链接</description></item>
        /// <item><description>保持应用内容的独立性和安全性</description></item>
        /// </list>
        /// 
        /// <para><strong>禁用时的行为：</strong></para>
        /// <list type="bullet">
        /// <item><description>链接会在 WebView2 内部打开</description></item>
        /// <item><description>用户可能离开当前显示的内容</description></item>
        /// <item><description>需要提供后退导航功能</description></item>
        /// </list>
        /// 
        /// <para><strong>安全考虑：</strong></para>
        /// 建议在内容预览、文档查看等场景下启用此选项，防止恶意链接在应用内执行。
        /// </remarks>
        public bool UseExternalBrowserForLinks { get; set; } = true;

        #endregion

        #region 初始化配置

        /// <summary>
        /// 自动加载欢迎页面
        /// </summary>
        /// <value>
        /// <c>true</c>: 初始化完成后自动显示欢迎页面<br/>
        /// <c>false</c>: 初始化完成后保持空白，等待手动加载内容
        /// </value>
        /// <remarks>
        /// <para><strong>启用时的行为：</strong></para>
        /// <list type="bullet">
        /// <item><description>调用 <see cref="MarkdownViewManager.InitializeAsync"/> 后自动显示默认欢迎页面</description></item>
        /// <item><description>提供友好的初始用户体验</description></item>
        /// <item><description>显示应用名称和使用提示</description></item>
        /// </list>
        /// 
        /// <para><strong>禁用时的行为：</strong></para>
        /// <list type="bullet">
        /// <item><description>初始化后 WebView2 保持空白状态</description></item>
        /// <item><description>需要手动调用相应的显示方法来加载内容</description></item>
        /// <item><description>适合需要立即显示特定内容的场景</description></item>
        /// </list>
        /// 
        /// <para><strong>适用场景：</strong></para>
        /// <list type="bullet">
        /// <item><description>启用：独立预览应用、文档查看器</description></item>
        /// <item><description>禁用：嵌入式预览控件、即时内容显示</description></item>
        /// </list>
        /// </remarks>
        public bool AutoLoadWelcomePage { get; set; } = true;

        #endregion

        #region 安全和脚本配置

        /// <summary>
        /// 注入安全和功能禁用脚本
        /// </summary>
        /// <value>
        /// <c>true</c>: 注入脚本以禁用某些浏览器功能和快捷键<br/>
        /// <c>false</c>: 不注入额外脚本，保持原生浏览器行为
        /// </value>
        /// <remarks>
        /// <para><strong>注入的脚本功能包括：</strong></para>
        /// <list type="bullet">
        /// <item><description>禁用 F12 开发者工具快捷键</description></item>
        /// <item><description>禁用右键上下文菜单</description></item>
        /// <item><description>禁用文本选择和复制</description></item>
        /// <item><description>禁用页面缩放快捷键</description></item>
        /// <item><description>禁用页面刷新快捷键</description></item>
        /// <item><description>其他安全限制功能</description></item>
        /// </list>
        /// 
        /// <para><strong>安全优势：</strong></para>
        /// <list type="bullet">
        /// <item><description>防止用户通过浏览器功能绕过应用限制</description></item>
        /// <item><description>保护应用内容不被轻易复制或修改</description></item>
        /// <item><description>提供更加受控的用户体验</description></item>
        /// </list>
        /// 
        /// <para><strong>注意事项：</strong></para>
        /// <list type="bullet">
        /// <item><description>可能影响辅助功能的使用</description></item>
        /// <item><description>在开发和调试阶段建议禁用</description></item>
        /// <item><description>脚本注入失败不会阻止应用正常运行</description></item>
        /// </list>
        /// </remarks>
        public bool InjectSecurityScripts { get; set; } = true;

        #endregion

        #region 用户交互配置

        /// <summary>
        /// 拦截UI层键盘事件
        /// </summary>
        /// <value>
        /// <c>true</c>: 在 WinForms 层面拦截并禁用所有键盘输入<br/>
        /// <c>false</c>: 允许正常的键盘交互
        /// </value>
        /// <remarks>
        /// <para><strong>启用时的行为：</strong></para>
        /// <list type="bullet">
        /// <item><description>所有键盘事件在 WebView2 控件层面被拦截</description></item>
        /// <item><description>设置 <c>e.Handled = true</c> 和 <c>e.SuppressKeyPress = true</c></description></item>
        /// <item><description>在调试模式下输出被拦截的按键信息</description></item>
        /// </list>
        /// 
        /// <para><strong>安全作用：</strong></para>
        /// <list type="bullet">
        /// <item><description>防止用户通过快捷键访问浏览器功能</description></item>
        /// <item><description>阻止 F12、Ctrl+Shift+I 等开发者工具快捷键</description></item>
        /// <item><description>禁用 Ctrl+U 查看源代码等功能</description></item>
        /// <item><description>阻止 F5 刷新、Ctrl+R 重载等操作</description></item>
        /// </list>
        /// 
        /// <para><strong>副作用：</strong></para>
        /// <list type="bullet">
        /// <item><description>可能影响辅助功能的键盘导航</description></item>
        /// <item><description>禁用了一些用户期望的标准快捷键</description></item>
        /// <item><description>对用户体验可能产生负面影响</description></item>
        /// </list>
        /// 
        /// <para><strong>建议使用场景：</strong></para>
        /// <list type="bullet">
        /// <item><description>高安全性要求的内容展示</description></item>
        /// <item><description>防止用户干预的演示应用</description></item>
        /// <item><description>受控环境下的内容浏览</description></item>
        /// </list>
        /// </remarks>
        public bool InterceptUIKeyboard { get; set; } = true;

        #endregion

        #region WebView2 原生设置配置

        /// <summary>
        /// 禁用默认右键上下文菜单
        /// </summary>
        /// <value>
        /// <c>true</c>: 禁用 WebView2 的默认右键菜单<br/>
        /// <c>false</c>: 显示完整的浏览器右键菜单
        /// </value>
        /// <remarks>
        /// <para><strong>禁用时的效果：</strong></para>
        /// <list type="bullet">
        /// <item><description>用户右键点击时不会显示任何菜单</description></item>
        /// <item><description>无法通过右键菜单访问"后退"、"前进"、"刷新"等功能</description></item>
        /// <item><description>无法通过右键菜单"查看源代码"或"检查元素"</description></item>
        /// <item><description>无法通过右键菜单复制文本或保存图片</description></item>
        /// </list>
        /// 
        /// <para><strong>安全优势：</strong></para>
        /// <list type="bullet">
        /// <item><description>防止用户通过右键菜单访问不应该使用的功能</description></item>
        /// <item><description>保护页面内容不被轻易复制</description></item>
        /// <item><description>提供更加简洁的用户界面</description></item>
        /// </list>
        /// 
        /// <para><strong>对应 WebView2 设置：</strong></para>
        /// <c>CoreWebView2Settings.AreDefaultContextMenusEnabled = !DisableDefaultContextMenu</c>
        /// </remarks>
        public bool DisableDefaultContextMenu { get; set; } = true;

        /// <summary>
        /// 禁用开发者工具
        /// </summary>
        /// <value>
        /// <c>true</c>: 完全禁用开发者工具功能<br/>
        /// <c>false</c>: 允许用户打开和使用开发者工具
        /// </value>
        /// <remarks>
        /// <para><strong>禁用时的效果：</strong></para>
        /// <list type="bullet">
        /// <item><description>F12 快捷键无法打开开发者工具</description></item>
        /// <item><description>Ctrl+Shift+I 快捷键失效</description></item>
        /// <item><description>右键菜单中的"检查元素"选项不可用</description></item>
        /// <item><description>程序化调用开发者工具相关API将失败</description></item>
        /// </list>
        /// 
        /// <para><strong>安全重要性：</strong></para>
        /// <list type="bullet">
        /// <item><description>防止用户查看和修改页面DOM结构</description></item>
        /// <item><description>保护JavaScript代码和网络请求不被查看</description></item>
        /// <item><description>防止用户通过控制台执行恶意脚本</description></item>
        /// <item><description>是内容保护的重要安全措施</description></item>
        /// </list>
        /// 
        /// <para><strong>开发建议：</strong></para>
        /// <list type="bullet">
        /// <item><description>生产环境强烈建议启用</description></item>
        /// <item><description>开发和调试阶段可以临时禁用</description></item>
        /// <item><description>可以通过配置文件在不同环境中切换</description></item>
        /// </list>
        /// 
        /// <para><strong>对应 WebView2 设置：</strong></para>
        /// <c>CoreWebView2Settings.AreDevToolsEnabled = !DisableDevTools</c>
        /// </remarks>
        public bool DisableDevTools { get; set; } = true;

        /// <summary>
        /// 禁用默认脚本对话框
        /// </summary>
        /// <value>
        /// <c>true</c>: 禁用 JavaScript 弹窗对话框<br/>
        /// <c>false</c>: 允许 JavaScript 弹窗正常显示
        /// </value>
        /// <remarks>
        /// <para><strong>禁用的对话框类型：</strong></para>
        /// <list type="bullet">
        /// <item><description><c>alert()</c>: 警告对话框</description></item>
        /// <item><description><c>confirm()</c>: 确认对话框</description></item>
        /// <item><description><c>prompt()</c>: 输入对话框</description></item>
        /// <item><description><c>beforeunload</c>: 页面离开确认对话框</description></item>
        /// </list>
        /// 
        /// <para><strong>用户体验优势：</strong></para>
        /// <list type="bullet">
        /// <item><description>防止恶意脚本通过无限弹窗干扰用户</description></item>
        /// <item><description>避免意外的对话框中断用户操作</description></item>
        /// <item><description>提供更加流畅的浏览体验</description></item>
        /// <item><description>减少用户误操作的可能性</description></item>
        /// </list>
        /// 
        /// <para><strong>功能限制：</strong></para>
        /// <list type="bullet">
        /// <item><description>JavaScript 调用 alert() 等方法将静默失败</description></item>
        /// <item><description>某些需要用户确认的功能可能无法正常工作</description></item>
        /// <item><description>页面离开时不会有确认提示</description></item>
        /// </list>
        /// 
        /// <para><strong>适用场景：</strong></para>
        /// <list type="bullet">
        /// <item><description>内容展示和预览应用</description></item>
        /// <item><description>不需要用户交互的静态页面</description></item>
        /// <item><description>安全性要求较高的环境</description></item>
        /// </list>
        /// 
        /// <para><strong>对应 WebView2 设置：</strong></para>
        /// <c>CoreWebView2Settings.AreDefaultScriptDialogsEnabled = !DisableScriptDialogs</c>
        /// </remarks>
        public bool DisableScriptDialogs { get; set; } = true;

        /// <summary>
        /// 禁用页面缩放控制
        /// </summary>
        /// <value>
        /// <c>true</c>: 禁用用户缩放页面功能<br/>
        /// <c>false</c>: 允许用户自由缩放页面
        /// </value>
        /// <remarks>
        /// <para><strong>禁用的缩放方式：</strong></para>
        /// <list type="bullet">
        /// <item><description>Ctrl + 鼠标滚轮缩放</description></item>
        /// <item><description>Ctrl + Plus/Minus 键盘缩放</description></item>
        /// <item><description>Ctrl + 0 重置缩放</description></item>
        /// <item><description>触摸屏手势缩放</description></item>
        /// </list>
        /// 
        /// <para><strong>布局优势：</strong></para>
        /// <list type="bullet">
        /// <item><description>保持页面布局的设计一致性</description></item>
        /// <item><description>防止缩放导致的元素错位或重叠</description></item>
        /// <item><description>确保文本和图片按预期尺寸显示</description></item>
        /// <item><description>避免用户意外缩放造成的困扰</description></item>
        /// </list>
        /// 
        /// <para><strong>可访问性考虑：</strong></para>
        /// <list type="bullet">
        /// <item><description>可能影响视力不佳用户的使用体验</description></item>
        /// <item><description>建议在应用层面提供字体大小调节功能</description></item>
        /// <item><description>考虑提供高对比度主题支持</description></item>
        /// </list>
        /// 
        /// <para><strong>适用场景：</strong></para>
        /// <list type="bullet">
        /// <item><description>精确布局要求的应用界面</description></item>
        /// <item><description>固定尺寸的内容展示</description></item>
        /// <item><description>防止用户误操作的受控环境</description></item>
        /// </list>
        /// 
        /// <para><strong>对应 WebView2 设置：</strong></para>
        /// <c>CoreWebView2Settings.IsZoomControlEnabled = !DisableZoomControl</c>
        /// </remarks>
        public bool DisableZoomControl { get; set; } = true;

        #endregion

        #region 辅助方法

        /// <summary>
        /// 创建默认配置实例
        /// </summary>
        /// <returns>具有默认设置的配置实例</returns>
        /// <remarks>
        /// 返回的配置实例具有以下特点：
        /// <list type="bullet">
        /// <item><description>最高安全性设置</description></item>
        /// <item><description>最佳用户体验平衡</description></item>
        /// <item><description>适合大多数内容展示场景</description></item>
        /// </list>
        /// </remarks>
        public static MarkdownViewManagerOptions CreateDefault()
        {
            return new MarkdownViewManagerOptions();
        }

        /// <summary>
        /// 创建开发调试配置实例
        /// </summary>
        /// <returns>适合开发调试的配置实例</returns>
        /// <remarks>
        /// 开发配置的特点：
        /// <list type="bullet">
        /// <item><description>启用开发者工具</description></item>
        /// <item><description>允许右键菜单</description></item>
        /// <item><description>不拦截键盘事件</description></item>
        /// <item><description>不注入安全脚本</description></item>
        /// </list>
        /// </remarks>
        public static MarkdownViewManagerOptions CreateForDevelopment()
        {
            return new MarkdownViewManagerOptions
            {
                DisableDevTools = false,
                DisableDefaultContextMenu = false,
                InterceptUIKeyboard = false,
                InjectSecurityScripts = false,
                DisableScriptDialogs = false,
                DisableZoomControl = false
            };
        }

        /// <summary>
        /// 创建高安全性配置实例
        /// </summary>
        /// <returns>高安全性要求的配置实例</returns>
        /// <remarks>
        /// 高安全配置的特点：
        /// <list type="bullet">
        /// <item><description>禁用所有可能的用户交互</description></item>
        /// <item><description>最大化内容保护</description></item>
        /// <item><description>适合敏感内容展示</description></item>
        /// </list>
        /// </remarks>
        public static MarkdownViewManagerOptions CreateHighSecurity()
        {
            return new MarkdownViewManagerOptions
            {
                DisableDevTools = true,
                DisableDefaultContextMenu = true,
                InterceptUIKeyboard = true,
                InjectSecurityScripts = true,
                DisableScriptDialogs = true,
                DisableZoomControl = true,
                UseExternalBrowserForLinks = true
            };
        }

        #endregion
    }
}
